---
title: "Run Task"
api: "POST /api/v1/run-task"
description: "Requires an active subscription. Returns the task ID that can be used to track progress."
---

Creates a new browser automation task and returns the task ID that can be used to track progress.

## Request Body

<ParamField body="task" type="string" required>
  Instructions for what the agent should do. You can try it out at https://cloud.browser-use.com/
</ParamField>

<ParamField body="secrets" type="object">
  Dictionary of secrets to be used by the agent. Secrets are safely encrypted before storing in the database.
</ParamField>

<ParamField body="allowed_domains" type="array">
  List of domains that the agent is allowed to visit (e.g. ["google.com", "amazon.com", "*.skyscanner.com"]). <br/>
  We recommend using a wildcard to allow all subdomains of a domain (e.g. "*.skyscanner.com"). <br/>
  If not set, the agent will be allowed to visit all domains (not recommended if you are using secrets).
</ParamField>

<ParamField body="browser_profile_id" type="string">
  ID of the browser profile to use. If not set, the default profile will be used.
</ParamField>

<ParamField body="save_browser_data" type="boolean" default="false">
  If set to True, the browser cookies and other data will be saved. Cookies are safely encrypted before storing in the database.
</ParamField>

<ParamField body="structured_output_json" type="string">
  If set, the agent will use this JSON schema as the output model (see example here: https://docs.browser-use.com/cloud/implementation#structured-output-example).
</ParamField>

<ParamField body="llm_model" type="string" default="gpt-4.1">
  LLM model to use. 
  Available options: 
  - gpt-4o
  - gpt-4o-mini
  - gpt-4.1
  - gpt-4.1-mini
  - gemini-2.5-flash
  - claude-sonnet-4-20250514
</ParamField>

<ParamField body="use_adblock" type="boolean" default="true">
  If set to True, the agent will use an adblocker.
</ParamField>

<ParamField body="use_proxy" type="boolean" default="true">
  If set to True, the agent will use a (mobile) proxy. Note that proxy is required for captcha solving, so if you disable proxy, you will not be able to solve captchas.
</ParamField>

<ParamField body="proxy_country_code" type="string" default="us">
  Country code for residential proxy. Must be one of: 'us', 'fr', 'it', 'jp', 'au', 'de', 'fi', 'ca'. Default is 'us'.
</ParamField>

<ParamField body="highlight_elements" type="boolean" default="true">
  If set to True, the agent will highlight the elements on the page.
</ParamField>

<ParamField body="included_file_names" type="array">
  File names to include in the task (note: use uploads/presigned-url endpoint to upload the files first!). E.g. ['file1.txt', 'file2.csv']
</ParamField>

<ParamField body="browser_viewport_width" type="integer" default="1280">
  Width of the browser viewport in pixels. Default is 1280.
</ParamField>

<ParamField body="browser_viewport_height" type="integer" default="960">
  Height of the browser viewport in pixels. Default is 960.
</ParamField>

<ParamField body="max_agent_steps" type="integer" default="75">
  Maximum number of agent steps to take. Default is 75. Maximum is 200.
</ParamField>

<ParamField body="enable_public_share" type="boolean" default="false">
  If set to True, enables public sharing of the task execution. When enabled, a public_share_url will be generated that allows others to view the task results without authentication.
</ParamField>

<ParamField body="metadata" type="object">
  Optional dictionary of string key-value pairs for custom tagging. Max 10 pairs. Keys: strings (max 100 chars, non-empty). Values: strings (max 1000 chars).
</ParamField>

## Response

<ResponseField name="id" type="string">
  The unique identifier for the created task.
</ResponseField>


<RequestExample>

```python python
import requests

url = "https://api.browser-use.com/api/v1/run-task"

payload = {
    "task": "<string>",
    "secrets": {},
    "allowed_domains": ["<string>"],
    "save_browser_data": True,
    "structured_output_json": "<string>",
    "llm_model": "gpt-4o",
    "use_adblock": True,
    "use_proxy": True,
    "proxy_country_code": "us",
    "highlight_elements": True,
    "included_file_names": ["<string>"],
    "browser_viewport_width": 123,
    "browser_viewport_height": 123,
    "max_agent_steps": 123,
    "enable_public_share": True,
    "metadata": {
        "campaign": "q4-automation",
        "team": "marketing"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
```

```bash cURL
curl --request POST \
  --url https://api.browser-use.com/api/v1/run-task \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "task": "<string>",
  "secrets": {},
  "allowed_domains": [
    "<string>"
  ],
  "save_browser_data": true,
  "structured_output_json": "<string>",
  "llm_model": "gpt-4o",
  "use_adblock": true,
  "use_proxy": true,
  "proxy_country_code": "us",
  "highlight_elements": true,
  "included_file_names": [
    "<string>"
  ],
  "browser_viewport_width": 123,
  "browser_viewport_height": 123,
  "max_agent_steps": 123,
  "enable_public_share": true,
  "metadata": {
    "campaign": "q4-automation",
    "team": "marketing"
  }
}'
```

```javascript javascript 
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"task":"<string>","secrets":{},"allowed_domains":["<string>"],"save_browser_data":true,"structured_output_json":"<string>","llm_model":"gpt-4o","use_adblock":true,"use_proxy":true,"proxy_country_code":"us","highlight_elements":true,"included_file_names":["<string>"],"browser_viewport_width":123,"browser_viewport_height":123,"max_agent_steps":123,"enable_public_share":true,"metadata":{"campaign":"q4-automation","team":"marketing"}}'
};

fetch('https://api.browser-use.com/api/v1/run-task', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

```
</RequestExample>

<ResponseExample>
    ```json 200
    {
      "id": "task_1234567890abcdef"
    }
    ```

    ```json 422
    {
    "detail": [
        {
        "loc": [
            "<string>"
        ],
        "msg": "<string>",
        "type": "<string>"
        }
    ]
    }
    ```
</ResponseExample>
